Skip to content

audit: site-wide honesty pass + sketch tool fixes (Wave 1)#5

Merged
hushamsaeed merged 1 commit into
mainfrom
audit-wave-1
May 2, 2026
Merged

audit: site-wide honesty pass + sketch tool fixes (Wave 1)#5
hushamsaeed merged 1 commit into
mainfrom
audit-wave-1

Conversation

@hushamsaeed
Copy link
Copy Markdown
Contributor

Findings from a 6-agent autonomous audit (engineering, content/strategy, cross-repo, package code, sketch UX/a11y, codex second-opinion). Each load-bearing claim was verified by reproduction before acting.

Site copy honesty

  • /architecture/ H1 softened from "Bank-Grade Platform Architecture" → "Reference architecture for bank-grade internal-tooling fleets" + v0.1.0-vs-target callout
  • 10× "# Part X" demoted to "## Part X" → page now has 1 H1 instead of 11
  • Removed duplicate six-commitments recap from §4 (links to manifesto)
  • starter-api §46 stack aligned to shipped Go 1.25 + chi + pgx (was Go 1.23 + Fiber + GORM)
  • OTel auto-instrumentation list aligned (chi+pgx, not Fiber+GORM)
  • Launch H1 → "first SDK release"; reframed "everything on public registry" → "SDKs on registries; substrate from source"
  • /sdk/ index: per-package status column added (all v0.1.0 today)
  • /tools/: trimmed 5× "coming soon" → 2 (OTel Config + CloudEvents Validator); softened "Excalidraw (looks amateur)" punch
  • /examples/access-requests/: disclosed dev-cookie-shim limitation
  • /start/try-it/: dropped non-existent Homebrew tap, replaced helm-OCI step with working git-clone path; helm-OCI flow moved into v1.0-target caution

Engineering

  • IFrameTool full-bleed via JS measurement instead of broken 100vw + calc(50% − 50vw) (was clipping iframe -233px off viewport on splash template)
  • Forwards parent location.hash into iframe so /tools/sketch/#d=… share links work end-to-end
  • Removed sandbox="allow-scripts allow-same-origin allow-downloads" (Chromium warns; both flags together negates sandbox; iframe is same-origin anyway)
  • check.yml workflow: minimal permissions: contents:read
  • Stale "Spectral Medium" comment + IBM Plex Mono fallback removed
  • Site theme-color meta added

Sketch tool (public/tools/sketch-app.html)

  • Toolbar flex-wrap: wrap on narrow viewports (was clipping Copy-share-link off-screen at 390px)
  • "Empty" example actually empty (was rendering an empty cite-only SVG; placeholder didn't show)
  • Share-link encoding chunked to 8KB, 64KB DSL cap; bad hash flashes error instead of silent default fallback
  • Status: role="status" aria-live="polite", distinct ✕/● glyph (not just color), replaceChildren updates (no innerHTML)
  • Added visually-hidden <h1>, <main> landmark, <label for> on example select, autofocus on textarea (primary surface)
  • Renders placeholder when DSL parses to 0 nodes (was rendering empty cite-only SVG)

Verifications run before commit

Claim Method Result
ghcr.io platform 401 curl confirmed
/sdk/ts/ 404 curl confirmed
homebrew-tap 404 curl confirmed
11 H1s on /architecture/ grep confirmed
Iframe clipped -233px playwright measurement confirmed
Same-row edge bug sketch CLI repro confirmed (deferred to Wave 2 sketch v0.1.1)
Sharp libvips LGPL transitive npm view confirmed (note added in v0.1.0 launch about MIT scope)
Iframe full-bleed fix playwright remeasure x=0, width=1440 ✓
Mobile toolbar wrap playwright 390x844 screenshot clean ✓
Share-link round-trip playwright copy → new context navigate DSL preserved ✓

Test plan

  • pnpm lint clean
  • pnpm build clean (26 pages)
  • Iframe full-bleed: desktop x=0 width=1440 viewport-spanning
  • Mobile (390×844) toolbar wraps without clipping
  • Share-link round-trip works through /tools/sketch/ parent → iframe
  • Live verify after deploy

🤖 Generated with Claude Code

Findings from a 6-agent autonomous audit (engineering, content/strategy,
cross-repo, package code review, sketch UX/a11y, codex second-opinion).
Verified each load-bearing claim before acting (ghcr.io 401, /sdk/ts/ 404,
brew tap 404, 11 H1s on /architecture/, iframe -233px desktop clip, sketch
same-row edge bug, Sharp libvips LGPL transitive).

Site copy honesty:
- Architecture H1: "Bank-Grade Platform Architecture" -> "Reference architecture
  for bank-grade internal-tooling fleets" + v0.1.0-vs-target callout note.
  Demoted 10x "# Part X" -> "## Part X" (was 11 H1s, now 1).
- Removed duplicate six-commitments recap from §4 (links to manifesto).
- Aligned starter-api stack to shipped state (Go 1.25 + chi + pgx, not
  Go 1.23 + Fiber + GORM). Marked Temporal as v1.0 target.
- Fixed OTel auto-instrumentation list (chi+pgx, not Fiber+GORM).
- Launch H1: "bank-grade foundation" -> "first SDK release". Reframed
  "everything... on a public registry you can install from right now" to
  honest "SDKs on registries; substrate from source".
- Launch table CLI: pinned-version @v0.1.1 -> @latest (avoids drift claim).
- Try-it: kept "Stand it up in an afternoon" but rewrote step 2 to use
  git-clone + values-dev.yaml (the path that works at v0.1.0); helm-OCI
  flow moved into a v1.0-target caution block. Dropped non-existent
  Homebrew tap line. Dropped Argo-CD reconcile step (it isn't shipped).
  Added kind-cluster prerequisites.
- /sdk/ index: added per-package status column (all v0.1.0 today).
- /tools/: trimmed 5 "coming soon" cards down to 2 (OTel Config + CloudEvents
  Validator) per strategist call. Softened "Excalidraw (looks amateur)"
  punch-down. Sketch promoted to its own H2 from the tools/diagrams pair.
- /examples/access-requests/: disclosed dev-cookie-shim limitation.
- Stale "Spectral" comment in astro.config -> IBM Plex Sans.
- Dropped IBM Plex Mono fallback from theme.css (JetBrains Mono is canonical).

Engineering:
- IFrameTool.astro: fixed full-bleed via JS measurement instead of
  100vw + calc(50% - 50vw) trick (which misaligns with Starlight's
  splash-template left-anchored content column, off-screen left -233px).
  Also: forwards parent location.hash into iframe src so /tools/sketch/
  share links route the encoded DSL into the embedded tool.
- Removed iframe sandbox= attr: `allow-scripts + allow-same-origin`
  together negates sandbox and Chromium warns. Same-origin anyway.
- check.yml: added permissions: contents:read minimal token scope.
- index.md: title "Plinth" (-> rendered as "Plinth | Plinth") replaced
  with the tagline. Added theme-color meta site-wide.

Sketch tool (public/tools/sketch-app.html):
- Toolbar wraps on mobile (was clipping Copy share link off-screen).
- "Empty" example now actually empty (was rendering a non-empty SVG with
  just the cite floating; placeholder text wasn't shown).
- Share-link encoding chunked to 8KB, with a 64KB DSL cap.
- Bad hash now flashes "share link malformed" instead of silently falling
  through to default.
- Status: aria-live=polite, distinct ✕ vs ● glyph for err/ok (not just
  color). Updates via replaceChildren (no innerHTML) so SR doesn't
  over-announce.
- Added <h1 visually-hidden>, wrapped editor in <main>, <label for>
  on the example select, autofocus on textarea (primary surface).
- Fixed render: shows placeholder when DSL parses to 0 nodes (was
  rendering an empty cite-only SVG).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@hushamsaeed hushamsaeed merged commit 2a9f9e3 into main May 2, 2026
1 check passed
@hushamsaeed hushamsaeed deleted the audit-wave-1 branch May 2, 2026 08:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant